Creating documentation templates files

Introduction
When you document symbols in your source code, SNiFF+ uses documentation template files to generate documentation frames for each symbol. There is one documentation template file for each type of symbol.
To create documentation template files, complete these steps:

Customize an existing template file or create a new one.
Name it.
Determine where to store it in your file system.
Specify its location in SNiFF+.

Step 1: Customize documentation template files
There are two ways in which you can customize documentation template files:

- by using HTML tags for layout
- by using macros to extract information from SNiFF+'s Symbol Table and comments from your source files

In this section, you will find out which HTML tags are recognized by SNiFF+ and which macros you can use for extracting symbolic information and comments.
Using HTML tags in documentation template files
SNiFF+'s Documentation Editor recognizes the following HTML tags:
(In the following list, only the starting tags are shown.)
<p>
<sub>, <sup>
<code>
<b>, <i>, <em>, <cite>, <strong>
<h1> ... <h6>
<center>
<plaintex>
<pre>
<ul>
<ol>
<dt>
<dd>
<body>
<html>
<!--
Note that you can use other HTML tags in your documentation template files as well. You may want to do so if you plan to browse your documentation template files with an HTML browser. SNiFF+ will ignore any HTML tags that are not listed above.
Maintaining formatting (newline) in HTML
Use the <pre> tag to maintain formatting (newline) in HTML. For example:
<pre><SNiFFINSERT CODE="@FIRST_COMMENT@"></pre>
(The macro used in this example is described below.)
Using macros in documentation template files
You can use the macros listed in the following table to incorporate information from SNiFF+'s Symbol Table into your documentation. Please note that macro expansion only works when the Use Parser Comments for Syntax Highlighting checkbox in the Project Attributes > Parser view is selected.
Each macro is associated with a particular program scope (see table). If you set the macro in an incorrect scope, SNiFF+ will not be able to expand the macro, and you will get an error message when trying to generate documentation frames.
For example, suppose you want to list the base classes of each class in your source code. You would use the @BASE_CLASS_LIST@ macro to do so. Since this macro has a class scope, you would have to set this macro in the documentation template file used for documenting classes. Then, whenever documentation frames are generated for classes in your source code, the @BASE_CLASS_LIST@ macro is expanded in each documentation frame. See also Step 2: Name your documentation template file.
Macros that have a symbol scope can be set in any documentation template file.
(To see how to set macros in documentation template files, please refer to the example template file on page 320)

.

Macro | Scope | Description
@BASE_CLASS_LIST@ | class | Comma-separated list of the base classes of the class.
@BASE_CLASS_FULL_LIST@ | class | Numbered list of the base classes of the class.
@CLASSES_IN_FILE@ | file | List of all classes in the documentation file's corresponding source file(s). Note that this macro can only be set in the Header.dtmpl template file (located in $SNIFF_DIR/config/docu ).
@COMMENT_BEFORE_DEF@ | symbol | Extract the comments that precede the definition of the symbol in the source file. Note that the characters / and * are not extracted from the comment text.
@COMMENT_AFTER_DEF@ | symbol | Extract the first comment lines that follow the definition of the symbol in the source file. Code lines are allowed between the definition of the symbol and the first comment lines. Note that the characters / and * are not extracted from the comment text. Note: We recommend not using both the @COMMENT_BEFORE_DEF@ and @COMMENT_AFTER_DEF@ macros for the same symbol, since comments following the symbol's definition may belong to the next symbol's definition. To avoid this ambiguity, always place comment lines either before or after a symbol's definition and use the appropriate macro to extract them.
@COMMENT_BEFORE_DEF_ FROM(X)TO(Y)@ | symbol | Extract all comments that precede the definition of the symbol and are between the user-defined tags X and Y. These tags must be alphanumeric and part of the comment that is being extracted. Note that the characters / and * are not extracted from the comment text.
@COMMENT_AFTER_DEF_ FROM(X)TO(Y)@ | symbol | Extract all comments that follow the definition of the symbol and are between the user-defined tags X and Y. These tags must be alphanumeric and part of the comment that is being extracted. Note that the characters / and * are not extracted from the comment text. Note: See the note in the description of the @COMMENT_AFTER_DEF@ macro.
@DER_CLASS_LIST@ | class | Comma-separated list of the derived classes of the class.
@DER_CLASS_FULL_LIST@ | class | Numbered list of the derived classes of the class.
@ENUM_LIST@ | enumeration | Comma-separated list of the enumeration items of the enumeration.
@ENUM_FULL_LIST@ | enumeration | Numbered list of the enumeration items of the enumeration.
@FIRST_COMMENT@ | file | Extract the first comment lines in the source file. These comment lines must be the first non-empty lines in the file. Note that the characters / and * are not extracted from the comment text. Note that this macro can only be set in the Header.dtmpl template file (located in $SNIFF_DIR/config/docu ).
@INSTVAR_LIST@ | class | Comma-separated list of the instance variables in the class.
@INSTVAR_FULL_LIST@ | class | Numbered list of the instance variables in the class. The signatures of the variables are included in the list.
@METHOD_LIST@ | class | Comma-separated list of the methods defined in the class.
@METHOD_FULL_LIST@ | class | Numbered list of the methods defined in the class. The signatures of the methods are included in the list.
@PARAM_LIST@ | method or function | List of parameter types of a function or method.
@PARAM_LIST_WITH_ NAME@ | method or function | List of parameter types and parameter names of a function or method.
@RET_VAL@ | method or function | Return value of the function or method.
@SNIFF_DATE@ | file | SNiFF+ version date.
@SNIFF_VERSION@ | file | SNiFF+ version number.
@SYMBOL_MEMBEROF@ | class | Class name of the symbol.
@SYMBOL_NAME@ | symbol | Name of the symbol.
@SYMBOL_TYPE@ | symbol | Type of the symbol (e.g., instance variable, global variable).
@TYPE_LIST@ | class | Comma-separated list of typedefs in the class.
@TYPE_FULL_LIST@ | class | Numbered list of typedefs in the class. The signatures of the typedefs are included in the list.

Step 2: Name your documentation template file
There are two points to keep in mind when naming documentation template files:

- Template files must have the same names as the symbol types for which they are designed.
- The names of symbol types are hard-coded in SNiFF+.

For example, suppose you have created and want to name a template file for subroutines in FORTRAN. In SNiFF+, the symbol type for subroutines is subroutine , and you would therefore name the template file subroutine.dtmpl (all template files have the extension dtmpl ). The following table lists the names that you must use for your C/C++, FORTRAN, IDL, Java and Ada documentation template files.

C/C++ | FORTRAN | IDL | Java | Ada | Default template file/symbol type
macro | -- | macro | -- | -- | Macro
enum | -- | enum | -- | enum | Enumeration
typedef | -- | -- | -- | typedef | TypeDef
variable | variable | -- | -- | object | GlobalVariable
function | subroutine | -- | -- | subprog | GlobalFunction
class | common_block | interface | class | package | Class
struct | block | struct | interface | record | Struct
inst_var | -- | attribute | field | pkg object | InstanceVariable
methodDef | method | method | method | pkg subprog def | Method
union | union | union | -- | -- | Union

The last column in the table lists the names of the default template files used for the listed symbol types. SNiFF+ uses the default template files if it can't find your template files. See also How SNiFF+ searches for documentation template files.
Step 3: Determine where to store template files
You have two options for storing your documentation template files:

- If you want to use a template file for all of your SNiFF+ projects, store it in any directory in your file system.
- If you want to make a template file project-specific, store it in the project directory of a SNiFF+ project and then add it to the project. The template file is then valid for this project only.

For details about storing and specifying the location of template files, please refer to Step 4: Specify the location of template files.
Step 4: Specify the location of template files
For template files stored in a template directory

Create a template directory and use the following table to name its language-specific subdirectories:

C/C+ | FORTRAN | IDL | Java | Ada
Ansi_C/C++ (Create a directory called Ansi_C and, in it, a subdirectory called C++ ). | FORTRAN_77 | IDL | Java | Ada9X

If your language is not listed in the above table, launch SNiFF+. Then,

2. Load a project that contains source files in the language you want to document.
3. Create a language-specific subdirectory and name it according to the name used in the Language drop down in the Symbol Browser, Hierarchy Browser and in the Cross Referencer.
4. Store your template file in the appropriate language-specific subdirectory.
5. Enter the template directory's path in the Template Directory field in the Documentation Editor view of the Preferences dialog.

For template files stored in a project directory

Store the template file in the

<project>/docu/dtmpl directory. <project> is the name of project directory in the shared source working environment where the project's source files are stored.
Make sure that the Document Template file type has been loaded into the project. If it hasn't, load it into the project.
Add the documentation template file to the project (by choosing the Add/Remove Files to/from <project>... command from the Project menu of the Project Editor).
How SNiFF+ searches for documentation template files
When you document a particular symbol in your source code, SNiFF+ searches for the appropriate documentation template file in three directories:

- If the Document Template file type is part of the current project, SNiFF+ first searches for the template file in the directory specified by the file type's Directory attribute (default value is

/docu/tmpl ).
- If the file isn't found, SNiFF+ continues searching for it in the template directory specified in the Template Directory field in the Documentation Editor view of the Preferences dialog.
- If the template file isn't found, SNiFF+ continues searching for it in the default directory (
$SNIFF_DIR/config/docu ). This directory contains default documentation template files. If SNiFF+ cannot find the appropriate template file for the symbol you are documenting, it will use the Default.dtmpl default template file.
To illustrate this procedure, let's use the following figure with three different scenarios:

Scenario 1
You want to document a C++ source file that contains classes, enums and methods. SNiFF+ will use the following template files to create documentation frames:

class.dtmpl located in <project>/docu/dtmpl
enum.dtmpl located in the <template_directory>/Ansi_C/C++/dtmpl
Method.dtmpl located in $SNIFF_DIR/config/docu
Scenario 2
You want to document an IDL file that contains interfaces and methods. SNiFF+ will use the following template files to create documentation frames:

interface.dtmpl located in <template_directory>/IDL
method.dtmpl located in <template_directory>/IDL
Scenario 3
You want to document a FORTRAN file that contains common blocks and methods. SNiFF+ will use the following template files to create documentation frames:

Class.dtmpl located in $SNIFF_DIR/config/docu
Method.dtmpl located in $SNIFF_DIR/config/docu
Sample documentation template file

| Description
<SNiFFSYMBOL TYPE="Class" NAME=" " SSTATUS="new" DSTATUS="empty" ATTRIBS="true"> | All documentation template files must begin with this header information. This is used for internal management of documentation frames. Do not modify any of its attributes.
<SNiFFSECT SNAME="Symbol Name"> | The definition of a Section in the symbol's documentation frame is contained between the start tag (code to the left) and </SNiFFSECT> . This particular Section is called Symbol Name. It tells SNiFF+ to insert the name of the symbol at the top of the documentation frame. Do not modify a Section's start tag.
<center> <h2> | You can change or add HTML tags in any Sections as desired.
<SNiFFINSERT CODE="@SYMBOL_NAME@"> | SNiFF+ macro directive that tells SNiFF+ to expand the macro @SYMBOL_NAME@. The expanded macro is then inserted after the directive's end tag. Macros can be set anywhere after a template file's header information.
</h2> </center> </SNiFFSECT> |
<SNiFFSECT SNAME="Symbol Sign"> <center> <h4> <SNiFFINSERT CODE="@RET_VAL@"> <SNiFFINSERT CODE="@SYMBOL_MEMBEROF@">:: <SNiFFINSERT CODE="@SYMBOL_NAME@">( <SNiFFINSERT CODE="@PARAM_LIST@">) </h4> </center> </SNiFFSECT> | This particular Section is called Symbol Sign. It tells SNiFF+ to insert the signature of the symbol right below its name. Do not modify any of the attributes in this Section's definition. HTML tags are used for layout.
<SNiFFSECT SNAME="Parameters"> <h4> Parameters: <em><SNiFFINSERT CODE="@PARAM_LIST@"></em> </h4> | This Section is the first one in the documentation frame that contains editable text (see below). The Section Identifier for this Section is Parameters. Note that you can modify the name of this section (given by SNAME attribute). In general, you can modify the SNAME attribute for all sections except for Symbol Name and Symbol Sign.
<SNiFFSECTT> <pre>XXXXX_Parameters </pre> </SNiFFSECTT> | The definition of the Section Text field of a Section is contained between <SNiFFSECTT> and </SNiFFSECTT>. Text contained in the Section Text field is editable in the Documentation Editor.
</SNiFFSECT> |
</SNiFFSYMBOL> | All documentation template files must end with this end tag.